home *** CD-ROM | disk | FTP | other *** search
/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / program / tjgold.zip / INSTALL.004 / FGUSER22.TXT < prev    next >
Text File  |  1995-05-29  |  8KB  |  197 lines
  1.                               Managing INI Files
  2.  
  3.                                  "What is fame? An empty bubble; gold?
  4.                                   A transient shining trouble"
  5.                                   Solitude, James Grainger, 1721-1766
  6.  
  7.      Introduction
  8.  
  9.           Look at almost any hard drive nowadays and you will find an
  10.      assortment of INI files. Initialization files are text files that
  11.      contain the variables related to an application or other program
  12.      information. Although INI files were popularized by Windows
  13.      applications, they are equally valuable to text-mode applications.
  14.  
  15.           An INI file is simply a structured text file designed for
  16.      storing strings and numbers. An INI file consists of one or more
  17.      sections with related entries (keynames) within the section.
  18.      Following is an example of an .INI file.
  19.  
  20.           [DIRECTORIES]
  21.           Programs=C:\ACCOUNTS
  22.           Data=C:\ACCOUNTS\FILES
  23.           Temp=C:\
  24.  
  25.           [EXTENSIONS]
  26.           Ext1=DBF; database files
  27.           Ext2=DAT
  28.           Ext3=RES
  29.  
  30.           To take advantage of Gold's INI support, you need to
  31.      understand the various components in an INI file. An INI file is
  32.      composed of sections, keys, values and comments.
  33.  
  34. The Section
  35.  
  36.           The name (header) of a section. The enclosing brackets ([ ])
  37.      are required, and the left bracket must be in the leftmost column
  38.      on the screen. In the above example, there are two sections:
  39.      DIRECTORIES and EXTENSIONS.
  40.  
  41. The Entry Name
  42.  
  43.           The name of an entry, which can consist of any combination of
  44.      letters and digits. The entry name is usually followed by an '='
  45.      character. In the above example, the DIRECTORIES section has three
  46.      entries: Programs, Data and Temp.
  47.  
  48. The Value
  49.  
  50.           The value of each entry, which can be an integer, a string or
  51.      a quoted string. This is the text which lies to the right of the
  52.      equals sign. In the above example, the Programs entry has the value
  53.      C:\ACCOUNTS.
  54.  
  55. The Comments
  56.  
  57.           Some entries include brief comments below the header or on the
  58.      same line as an entry. You can include comments anywhere in an .INI
  59.      file by prefacing the comment with a semicolon (;). Notice the
  60.      comment database files in the above example.
  61.  
  62. INI File Management
  63.  
  64.           INI files are not renowned for their speed!
  65.  
  66.           Gold provides two methods of creating and managing INI files.
  67.      If you are only accessing small amounts of data, the standard
  68.      access methods should suffice. However, if the application makes
  69.      repeated calls to an INI file, then the buffered routines will
  70.      offer improved performance.
  71.  
  72. Standard Routines
  73.  
  74.           Listed below are the standard routines for saving and loading
  75.      values in an INI file.
  76.  
  77.      GetIniString( Default, Section, Entry, FName: string ): string;
  78.  
  79.           Returns a string representing the data found using the defined
  80.           parameters.
  81.  
  82.      GetIniInt( Default, Section, Entry, FName: string ): integer;
  83.  
  84.           Returns an integer representing the data found using the
  85.           defined parameters.
  86.  
  87.      GetIniLong( Default, Section, Entry, FName: string ): longint;
  88.  
  89.           Returns a longint representing the data found using the
  90.           defined parameters.
  91.  
  92.      GetIniReal( Default, Section, Entry, FName: string ): real;
  93.  
  94.           Returns a real value representing the data found using the
  95.           defined parameters.
  96.  
  97.      WriteIniString( Section, Entry, EntryVal, FName: string ): integer;
  98.  
  99.           Updates the data defined by the passed parameters if both
  100.           section and entry are found. If either is not located the
  101.           entry and/or section are created accordingly. If the INI file
  102.           does not exist, one will be created. If any value other than
  103.           zero is returned, the write did not take place.
  104.  
  105.      GetIniSection( var SL: SingleLL; Section, FName: string): integer;
  106.  
  107.           Reads an entire section into the passed singly linked list. A
  108.           zero value indicates a successful read.
  109.  
  110.           Most of the above routines contain four common parameters:
  111.      Default, Section, Entry and Filename. The default parameter is what
  112.      the function will return to the application if the section or entry
  113.      is not located. The section parameter is the name of the section,
  114.      without the brackets ([ ]). The entry parameter is the entry name
  115.      of the data to be accessed. It is followed immediately by an equals
  116.      sign (=). The filename parameter is the name of the .INI file to
  117.      search in.
  118.  
  119.           Refer to the demo files DEMINI1.PAS and DEMINI2.PAS to see the
  120.      standard INI file routines in action.
  121.  
  122. Buffered Routines
  123.  
  124.           Each time a standard INI routine (discussed above) is called,
  125.      disk access is required. The buffered routines provide an
  126.      alternative method to improve performance when a lot of INI calls
  127.      are required. This method loads the entire INI file onto the heap,
  128.      where it remains until you remove it.
  129.  
  130.           Since some INI files can be extremely large, as a developer
  131.      you must concern yourself with the available amount of heap space.
  132.      You should first compare the amount of available heap space to the
  133.      size of the INI file to be loaded.
  134.  
  135.           Gold uses an internal list for the buffered routines. Remember
  136.      that any change made to an INI entry while using the buffered
  137.      routines must be saved to disk using SaveIni to actually be
  138.      retained.
  139.  
  140.      LoadIni(LFileName: string): integer;
  141.  
  142.           Loads an entire INI file into memory using the available heap
  143.           space. A zero value indicates success.
  144.  
  145.      UnLoadIni;
  146.  
  147.           Removes the previously loaded INI file from memory releasing
  148.           the heap space.
  149.  
  150.      PutIniString( Section, Entry, EntryVal:string ): integer;
  151.  
  152.           Modifies the value of the specfied entry.
  153.  
  154.      SaveIni( LFileName: pathstr;OverWrite:boolean ): integer;
  155.  
  156.           Writes the contents of the INI buffer back to disk for future
  157.           use. If OverWrite is set to false, a backup (.BAK) of the INI
  158.           file is created prior to the actual saving of the data being
  159.           held in memory, otherwise the original file is overwritten.
  160.  
  161.      ReadIniString( Default,Section,Entry:string ): string;
  162.  
  163.           Returns a string representing the data found by the defined
  164.           parameters.
  165.  
  166.      ReadIniInt( Default,Section,Entry:string ): integer;
  167.  
  168.           Returns an integer value representing the data found using the
  169.           defined parameters.
  170.  
  171.      ReadIniLong( Default,Section,Entry:string ): longint;
  172.  
  173.           Returns a longint value representing the data found using the
  174.           defined parameters.
  175.  
  176.      ReadIniReal( Default,Section,Entry:string ): real;
  177.  
  178.           Returns a real value representing the data found using the
  179.           defined parameters.
  180.  
  181.      ReadIniSection( var SL:SingleLL; Section:string): integer;
  182.  
  183.           Loads an entire section into the specified list. A zero value
  184.           indicates a successful read.
  185.  
  186. Error Codes
  187.  
  188.      LastIniError: integer;
  189.  
  190.           Returns the last error generated by the INI unit.
  191.  
  192. INI Colors
  193.  
  194.           Just to resolve your concerns, there are no colors to be
  195.      supported in the INI unit.
  196.  
  197.